LEGION Simulator API Help

Working with the API

  1. The API is only distributed as a "release" (a.k.a. "retail") build i.e. there is no debug information, symbol files etc.
    1. Debug builds of your applications can link to the API release build.
    2. You won't be able to debug inside the API's binaries.
  2. For projects using the API, add these entries to Configuration Properties (right-click on the project in Solution Explorer and select "Properties"), where [the API install path] is the folder containing the API SDK:
    1. Configuration Properties > General:
      1. Platform Toolset:
      2. Use of MFC:
      3. Character Set:
      • Visual Studio 2017 - Windows XP (v141_xp)
      • Use MFC in a Shared DLL
      • Use Multi-Byte Character Set
    2. Configuration Properties > C/C++ > General:
      1. Additional Include Directories:
      • [the API install path]\LEGION Simulator API\include
    3. Configuration Properties > Linker > General:
      1. Additional Include Directories:
      • [the API install path]\ LEGION Simulator API\dll\v141_xp\x64\Release-XP
      • [the API install path]\ LEGION Simulator API\lib\v141_xp\x64\Release-XP
    4. Configuration Properties > Linker > Input:
      1. Additional Dependencies:
      • LegionException_v141_xp.lib
      • LegionSimulator_v141_xp.lib
      • LegionSimulatorSupport_v141_xp.lib
      • LegionUtility_v141_xp.lib
      • LegnLicence_v141_xp.lib
      • LegnLicenceSupport_v141_xp.lib
  3. The API’s main simulation functions are in the LegionSimulator and LegionSimulatorSupport libraries. Headers for types and functions are installed here:

    API install path shown on the address bar.

  4. License support and query functions are provided through LegionLicenceSupport, headers are here:
  5. The API’s types and functions typically reside in the Legion::Simulator and Legion::Model namespaces. Please review the examples in Test Bench to see how the API’s types and functions are used to create and run LEGION simulations.
  6. Applications built with the API will require LEGION Simulator API entitlement while executing simulation functions. When running your applications, you must either:

    Be signed into the Client,

    or

    Have been signed into the Client within the last 7 days.

    Note: If you are not signed in and sign-in is required by the licence, the Client will prompt you to do sign in. Failure to sign in when prompted will prevent your applications from executing LEGION simulation functions.
  7. To use the API’s LEGION Simulation functions, your application must create an instance of ISimulator (declared in the Legion::Simulator namespace).

    Creating an ISimulator instance consumes licenses for LEGION Simulator API and LEGION Simulator products.

    1. The Test Bench shows how to do this in the BasicSimulator.hpp file’s BeginExample() method.

      The exact code is: 

      std::string sProductName_In = "LEGION Simulator API";
// Must be exactly this string (case-sensitive) to use LEGION Simulator API
std::string sProductVersion_In = Legion::LicenceSupport::CLegnLicenceSupport::GetProductVersion().AsString();
// Must match the current API version - use Licence Support function to ensure this
Legion::LicenceSupport::Simulator_API_ConnectionString::SimAPIPublicKeyPtr	pPublicKey_Out;
// Licence connection’s public encryption key goes here - use this to create a Licence Support instance for
// querying licence information
std::string sConnectionString_Out;
// Encrypted licence connection string goes here - use this when querying licence information
auto pSimulator = Legion::Simulator::CLegionSimulatorFactory::CreateSimulator(
hAssociatedWindow_IN, sProductName_In, sProductVersion_In, pPublicKey_Out, sConnectionString_Out );
// This creates a Legion::Simulator::ISimulatorPtr instance; LEGION simulation functions are mostly accessed through here
// A valid, non-null window handle (“associatedWindow”) is a required parameter.
// If window handle is null, CreateSimulator will fail.
    2. Note the use of the CLegionSimulatorFactory::CreateSimulator method to create an ISimulator instance.
      Required parameters are:
      • hAssociatedWindow Must be a non-null window handle
      • sProductName_In Must be exactly "LEGION Simulator API" - case sensitive
      • sProductVersion_In Legion::LicenceSupport:: CLegnLicenceSupport ::GetProductVersion().AsString()
    3. LEGION simulator instance is encapsulated in a smart pointer of type Legion::Simulator::ISimulatorPtr.
    4. Correct required parameters will yield a valid Legion::Simulator::ISimulatorPtr instance.
    5. If the licence parameters are incorrect, a licence exception is thrown, and the ISimulatorPtr instance is not created.
    6. To use license-query functions, always create a new public key for encrypting the license connection string.
    7. You should never reuse the key and connection string used to initialise the Simulator; doing so will result in an RSA exception:

      InvertibleRSAFunction: computational error during private key operation

    8. To avoid this exception, always generate a new public key and connection string before calling license-query functions, as is shown in the release notes’ Querying Licence Information topic.
    9. You only need to create the public key and connection string once for calling these functions.
Parent topic: LEGION Simulator API 2023 Help